<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>bmqt_correlationid Component</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javaScript" src="search/search.js"></script>
<link href="bdedox.css" rel="stylesheet" type="text/css"/>
    <style>
      div.hanging {
        padding-left: 0.75in;
        text-indent: -0.50in;
      }
      div.unhanging {
        text-indent:     0in;
      }
      a.glossary {
        font-weight: bold;
        font-style: italic;
      }
    </style>
</head>
<!--
<body onload='searchBox.OnSelectItem(0);'>
-->
<body>

<table border=2 cellspacing=0 cellpadding=0 align=center>
<tr>
 <td valign=top align=center>
 <p align=center><b><i>Quick Links:</i></b></p>
 </td>
 <td valign=top align=center>
 <p align=center>
<a class="qindex" href="group__bmqa.html" target="_blank">bmqa</a> | <a class="qindex" href="group__bmqpi.html" target="_blank">bmqpi</a> | <a class="qindex" href="group__bmqt.html" target="_blank">bmqt</a>
 </td>
 </tr>
 </table>

  </div>
<!-- Generated by Doxygen 1.7.1 -->
<div class="navigation" id="top">
  <div class="tabs">
    <ul class="tablist">
      <li><a href="components.html"><span>Main&nbsp;Page</span></a></li>
      <li><a href="components.html"><span>Components</span></a></li>
      <li><a href="namespaces.html"><span>Namespaces</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
</div>
<div class="header">
  <div class="summary">
<a href="#namespaces">Namespaces</a>  </div>
  <div class="headertitle">
<h1>Component bmqt_correlationid<br/>
<small>
[<a class="el" href="group__bmqt.html">Package bmqt</a>]</small>
</h1>  </div>
</div>
<div class="contents">

<p>Provide a value-semantic type usable as an efficient identifier.  
<a href="#_details">More...</a></p>
<table class="memberdecls">
<tr><td colspan="2"><h2><a name="namespaces"></a>
Namespaces</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">namespace &nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespacebmqt.html">bmqt</a></td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<dl class="user"><dt><b>Outline</b></dt><dd><ul>
<li>
<a href="#1">Purpose</a> </li>
<li>
<a href="#2">Classes</a> </li>
<li>
<a href="#3">Description</a> <ul>
<li>
<a href="#3.1">AutoValue</a> </li>
<li>
<a href="#3.2">Usage</a> <ul>
<li>
<a href="#3.2.1">Example 1: Correlating Responses</a> </li>
</ul>
</li>
</ul>
</li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="purpose"></a> <a class="anchor" id="1"></a> </dd></dl>
<dl class="user"><dt><b>Purpose: </b></dt><dd>Provide a value-semantic type usable as an efficient identifier. </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="classes"></a> <a class="anchor" id="2"></a> </dd></dl>
<dl class="user"><dt><b>Classes: </b></dt><dd><table class="doxtable">
<tr>
<td><a class="el" href="classbmqt_1_1CorrelationId.html">bmqt::CorrelationId</a> </td><td>correlation ID class.  </td></tr>
<tr>
<td><a class="el" href="structbmqt_1_1CorrelationIdLess.html">bmqt::CorrelationIdLess</a> </td><td>comparison functor for <code>CorrelationId</code> as map key  </td></tr>
<tr>
<td>bsl::hash </td><td>hash functor specialization  </td></tr>
</table>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="description"></a> <a class="anchor" id="3"></a> </dd></dl>
<dl class="user"><dt><b>Description: </b></dt><dd>This component implements a value-semantic class, <code><a class="el" href="classbmqt_1_1CorrelationId.html">bmqt::CorrelationId</a></code>, which can be used to identify any async operations. The correlationId contains a value (64-bit integer, raw pointer or sharedPtr) supplied by the application or uses an auto-assigned value. The type and the value of the correlationId can be set at construction time and changed later via the <code>setNumeric()</code>, <code>setPointer()</code> and <code>setSharedPointer</code> methods. Alternatively, a <code>CorrelationId::AutoValue</code> can be used to generate a unique correlationId from within the process. The <code><a class="el" href="structbmqt_1_1CorrelationIdLess.html">bmqt::CorrelationIdLess</a></code> comparison functor can be used for storing <code>CorrelationId</code> in a map as the key element; and a hash functor specialization is provided in the <code>bsl::hash</code> namespace. </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="autovalue"></a> <a class="anchor" id="description.autovalue"></a> <a class="anchor" id="3.1"></a> </dd></dl>
<dl class="user"><dt><b>AutoValue: </b></dt><dd>If the application doesn't care about the actual value of the correlation, AutoValue type can be used to create a unique correlationId. An AutoValue correlationId behaves exactly the same as any other type of correlation, with the exception that it's value can not be retrieved (but two correlationId can be still compared equal). <div class="fragment"><pre class="fragment">  <a class="code" href="classbmqt_1_1CorrelationId.html">bmqt::CorrelationId</a> corrId = <a class="code" href="classbmqt_1_1CorrelationId.html#a227367a2269c2b52955b7593ef6add6b">bmqt::CorrelationId::autoValue</a>();
</pre></div> </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="usage"></a> <a class="anchor" id="description.usage"></a> <a class="anchor" id="3.2"></a> </dd></dl>
<dl class="user"><dt><b>Usage: </b></dt><dd>This section illustrates intended use of this component. </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="example_1~3A_correlating_responses"></a> <a class="anchor" id="usage.example_1~3A_correlating_responses"></a> <a class="anchor" id="description.usage.example_1~3A_correlating_responses"></a> <a class="anchor" id="example_1"></a> <a class="anchor" id="usage.example_1"></a> <a class="anchor" id="description.usage.example_1"></a> <a class="anchor" id="3.2.1"></a> </dd></dl>
<dl class="user"><dt><b>Example 1: Correlating Responses: </b></dt><dd>Suppose that we have the following asynchronous messaging interface that we want to use to implement a basic request/response class. <div class="fragment"><pre class="fragment">  <span class="keyword">class </span>Messenger {

    <span class="keyword">public</span>:
      <span class="comment">// TYPES</span>
      <span class="keyword">typedef</span> bsl::function&lt;
        void(<span class="keywordtype">void</span>                       *buffer,
             <span class="keywordtype">int</span>                         bufferLength,
             <span class="keyword">const</span> <a class="code" href="classbmqt_1_1CorrelationId.html">bmqt::CorrelationId</a>&amp;  correlationId)&gt; MessageHandler;
          <span class="comment">// &#39;MessageHandler&#39; is an alias for a functor that handles received</span>
          <span class="comment">// messages consisting of the specified &#39;buffer&#39;, having the</span>
          <span class="comment">// specified &#39;bufferLength&#39;, as well as the specified associated</span>
          <span class="comment">// &#39;correlationId&#39; if the message is in response to a previously</span>
          <span class="comment">// transmitted message.</span>

      <span class="comment">// MANIPULATORS</span>
      <span class="keywordtype">void</span> sendMessage(<span class="keywordtype">void</span>                       *buffer,
                       <span class="keywordtype">int</span>                         bufferLength,
                       <span class="keyword">const</span> <a class="code" href="classbmqt_1_1CorrelationId.html">bmqt::CorrelationId</a>&amp;  correlationId);
          <span class="comment">// Send a message containing the specified &#39;buffer&#39; of the</span>
          <span class="comment">// specified &#39;bufferLength&#39;, associating the specified</span>
          <span class="comment">// &#39;correlationId&#39; with any messages later received in response.</span>

      <span class="keywordtype">void</span> setMessageHandler(<span class="keyword">const</span> MessageHandler&amp; handler);
          <span class="comment">// Set the functor to handle messages received by this object to</span>
          <span class="comment">// the specified &#39;handler&#39;.</span>
  };
</pre></div> First we declare a requester class. <div class="fragment"><pre class="fragment">  <span class="keyword">class </span>Requester {

      <span class="comment">// DATA</span>
      Messenger        *d_messenger_p;  <span class="comment">// used to send messages (held)</span>
      bslma::Allocator *d_allocator_p;  <span class="comment">// memory supply (held)</span>

      <span class="comment">// PRIVATE CLASS METHODS</span>
      <span class="keyword">static</span> <span class="keywordtype">void</span> handleMessage(<span class="keywordtype">void</span>                       *buffer,
                                <span class="keywordtype">int</span>                         bufferLength,
                                <span class="keyword">const</span> <a class="code" href="classbmqt_1_1CorrelationId.html">bmqt::CorrelationId</a>&amp;  correlationId);
          <span class="comment">// Handle the response message consisting fo the specified &#39;buffer&#39;</span>
          <span class="comment">// having the specified &#39;bufferLength&#39;, and associated</span>
          <span class="comment">// &#39;correlationId&#39;.</span>

    <span class="keyword">public</span>:
      <span class="comment">// TYPES</span>
      <span class="keyword">typedef</span> bsl::function&lt;void(void *buffer, int bufferLength)&gt;
                                                            ResponseCallback;
          <span class="comment">// &#39;ResponseCallback&#39; is an alias for a functor that is used to</span>
          <span class="comment">// process received responses consisting of the specified &#39;buffer&#39;</span>
          <span class="comment">// having the specified &#39;bufferLength&#39;.</span>

      <span class="comment">// CREATORS</span>
      <span class="keyword">explicit</span> Requester(Messenger        *messenger,
                         bslma::Allocator *basicAllocator);
          <span class="comment">// Create a &#39;Requester&#39; that uses the specified &#39;messenger&#39; to send</span>
          <span class="comment">// requests and receive responses, and the specified</span>
          <span class="comment">// &#39;basicAllocator&#39; to supply memory.</span>

      <span class="comment">// MANIPULATORS</span>
      <span class="keywordtype">void</span> sendRequest(<span class="keywordtype">void</span>                    *buffer,
                       <span class="keywordtype">int</span>                      bufferLength,
                       <span class="keyword">const</span> ResponseCallback&amp;  callback);
          <span class="comment">// Send a request consisting of the specified &#39;buffer&#39; having the</span>
          <span class="comment">// specified &#39;bufferLength&#39;, and invoke the specified &#39;callback&#39;</span>
          <span class="comment">// with any asynchronous response.</span>
  };
</pre></div> Then, we implement the constructor, setting the message handler on the provided <code>Messenger</code> to our class method. <div class="fragment"><pre class="fragment">  Requester::Requester(Messenger        *messenger,
                       bslma::Allocator *basicAllocator)
  : d_messenger_p(messenger)
  , d_allocator_p(basicAllocator)
  {
      d_messenger_p-&gt;setMessageHandler(&amp;Requester::handleMessage);
  }
</pre></div> Now, we implement <code>sendRequest</code>, copying the given <code>callback</code> into a correlationId that is provided to the messenger. <div class="fragment"><pre class="fragment">  <span class="keywordtype">void</span> Requester::sendRequest(<span class="keywordtype">void</span>                    *buffer,
                              <span class="keywordtype">int</span>                      bufferLength,
                              <span class="keyword">const</span> ResponseCallback&amp;  callback)
  {
      bsl::shared_ptr&lt;ResponseCallback&gt; callbackCopy;
      callbackCopy.createInplace(d_allocator_p, callback, d_allocator_p);
      <a class="code" href="classbmqt_1_1CorrelationId.html">bmqt::CorrelationId</a> correlationId(bsl::shared_ptr&lt;void&gt;(callbackCopy));
      d_messenger_p-&gt;sendMessage(buffer, bufferLength, correlationId);
  }
</pre></div> Finally, we implement our message handler, extracting the response callback from the correlationId, and invoking it with the received response message. <div class="fragment"><pre class="fragment">  <span class="keywordtype">void</span> Requester::handleMessage(<span class="keywordtype">void</span>                       *buffer,
                                <span class="keywordtype">int</span>                         bufferLength,
                                <span class="keyword">const</span> <a class="code" href="classbmqt_1_1CorrelationId.html">bmqt::CorrelationId</a>&amp;  correlationId)
  {
      assert(correlationId.<a class="code" href="classbmqt_1_1CorrelationId.html#a64cd67be07bfc68a2f0f9c8f3ea6bc3b">isSharedPtr</a>());
      ResponseCallback *callback = <span class="keyword">static_cast&lt;</span>ResponseCallback *<span class="keyword">&gt;</span>(
                                         correlationId.<a class="code" href="classbmqt_1_1CorrelationId.html#aa9d7eee54c28b010d94da76cfbe27722">theSharedPtr</a>().get());
      (*callback)(buffer, bufferLength);
  }
</pre></div> </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
</div>
<hr class="footer"/><address class="footer"><small>Generated on Thu Jun 15 2023 11:58:51 by&nbsp;
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.1 </small></address>
</body>
</html>
